Skip to main content

Recurring Payment Flow

Overview​

This section of documentation is intened for merchants that require recurring payments. The process can be broken up into two main parts- first the initiation of the recurring payment and second the submission of the recurring payment.

Initiate​

This is the first step in intiating a recurring payment, a payment mandate is created and a call to the /V2/Pay/Recurring endpoint is made containing information on the merchant, reference information, the transaction amount and the payment mandate.

Various verifications are made to the data and should all of them pass an initiation URL is returned. A recurring payment token is generatedand tied to the specified recurring payment mandate.

Request and Response snippet​

/v2/pay/recurring
{
  "echoData": "123",
  "traceId": "00000000000100001",
  "amount": 50000,
  "customerId": "customer01",
  "digitalWalletId": "00000000-0000-0000-0000-000000000000",
  "additionalData": "OPCD;3343",
  "delayedSettlement": false,
  "basket": [
    {
      "lineNumber": "1",
      "Id": "vod50",
      "barcode": "232323232",
      "quantity": 1,
      "description": "Vodacom R50 Voucher",
      "amountExVAT": 42500,
      "amountVAT": 7500
    }
  ],
  "Notifications": {
    "callbackUrl": "https://www.merchant.com/done",
    "notificationUrl": "https://www.merchant.com/notify"
  },
  "styling": {
    "logoUrl": "https://www.merchant.com/logo.png",
    "bannerUrl": "https://www.merchant.com/message.png",
    "theme": 0
  },
  "electronicReceipt": {
    "method": 0,
    "address": "27721234567"
  },
  "communication": {
    "msisdn": "27721234567",
    "message": "To make your payment please go the the following url: *{PaymentUrl}*"
  },
  "recurring": {
    "category": 2,
    "firstPaymentDate": "2021-04-01",
    "frequency": 6,
    "regularPaymentDay": 1,
    "amount": 20000,
    "paymentInstrumentMinimumValidityPeriod": 3
  }
}

Request Parameters​

echoData <string | optional> : Any value that needs to be echoed in the resulting notifications message and the message posted to the callback URL

traceId <string | mandatory> : (12 - 99 characters long) A unique identifier for transaction tracing purposes

amount <interger | mandatory> : The amount of the transaction in minor currency (integer number of cents) This value can be lower than the original purchase amount, but may not be higher than the purchase amount.

customerId <string | conditional> : (1 - 255 characters long) A value that uniquely identifies the transacting customer.

digitalWalletId <string | conditional> : (36 characters long) A value in UUID format that identifies the transacting customer. Only used if an existing digital wallet id exists.

additionalData <string | optional> : (9999 character maximum) Any other data required for the transaction using the VodaPay Gateway Additional Data Token format.Further tokens may be introduced in the future.

delaySettlement <boolean | mandatory> : This is a boolean value that determines if the payment is an immediate payment or a delayed payment.

basket <object | mandatory>

  • lineNumber <integer | mandatory> : A sequential number specifying the order in which the invoice item appears in the basket.

  • Id <string | mandatory> : (99 characters maximum) The identifier of the invoice item.

  • barcode <string | mandatory> : (99 characters maximum) An SKU or PLU code associated with the product.

  • quantity <integer | mandatory> : (12 - 99 characters long) This specifies how many of this specific item the customer has ordered.

  • description <string | mandatory> : (99 characters maximum) A short product description of the item

  • amountExVAT <integer | mandatory> : The price of the item, excluding VAT.

  • amountVAT <integer | mandatory> : The amount of VAT charged on the item.

notifications <object | optional>

  • callbackUrl <string | optional> : (255 character maximum) The URL which the result of the payment API call will be sent

  • notificationUrl <string | optional> : (255 character maximum) A URL to which the result of the payment will be sent to notify the integrating party of the result of the API call.

styling <object | optional>

  • logoUrl <string | optional> : (255 character maximum) This URL links to the merchant's logo image, which will be embedded into the payment page. The recommended size is 300 pixels wide and 100 pixels high, although other sizes will be resized on rendering.

  • bannerUrl <string | optional> : (255 character maximum) This URL links to an image of a message from the merchant, which will be embedded into the payment page. The recommended size is 300 pixels wide and 100 pixels high, although other sizes will be resized on rendering.

  • theme <integer | optional> : This contains an identifier to specify a theme to be used for rendering the payment page and the pages for callback URLs where applicable.If the theme referenced by this field is missing, the default theme will be used.

    • 0 - Default theme
    • 2 - Mini Apps theme

electronicReceipt <object | optional>

  • method <interger | optional> : The method in which the electronicReceipt is to be submitted to the customer

    • 0 = SMS
    • 1 = email

  • address <string | mandatory if "method" is populated> : (255 character maximum) The address which the e-receipt is to be sent

communication <object | optional>

  • msisdn <interger | optional> : (11 characters) The number that the sms will be sent to. It must include the country code while excluding the +. the customer

  • message <string | optional> : (99 character maximum) The message that will appear in the sms sent to the customer. Use the following term in the message where the url must appear: {PaymentUrl}.

recurring <object | mandatory>

  • category <integer | mandatory> : How the recurring payment will be applied. The codes are:

    • 1 = Instalments for a fixed period scheduled by the merchant
    • 6 = Ongoing fixed regular payments scheduled by the merchant
    • 11 = Ongoing variable payments scheduled by the merchant

  • firstPaymentDate <string | conditional> : (10 characters [ISO 8601]) THe date when the first payment is made. Mandatory for ongoing fixed regular payments

  • frequency <string | mandatory> : (99 characters maximum) The frequency of the recurring payments. The codes are:

    • 1 = Ad Hoc
    • 2 = Daily
    • 3 = Biweekly
    • 4 = Weekly
    • 5 = Fortnightly
    • 6 = Monthly
    • 7 = Quarterly
    • 8 = biannually
    • 9 = Annuanlly

  • regularPaymentDay <integer | conditional> :

    • Bi-weekly frequency - The first day of the week on which the recurring payment is scheduled. The second day is always two days later.
    • Weekly / Fortnightly frquency - The day of the week on which the recurring payment is scheduled. For - - - fortnightly payments, every second week is skipped.
    • Monthly frequency - The day of the month on which the recurring payment is scheduled.
    • Quarterly / Twice annually frquency - The day of the first month the recurring payment is scheduled. Subsequent payments will be scheduled for the same day of the month every 3 months or 6 months.
    • Annually frequency - The day of the year on which the recurring payment is scheduled.

    Mandatory for ongoing fixed regular payments, otherwise not used.

  • amount <integer | conditional> : The amount for each recurring payment. Mandatory for ongoing variable regular payments

  • paymentInstrumentMinimumValidityPeriod <integer | conditional> : The minimum number of months that the card must be valid (not expired) for from the date of initiation. This value is used to ensure that the card would not expire within the period that the merchant wants to schedule the recurring payment. The payment tokenisation will be declined if the number of months from the first payment date to the card's expiry date is less than this value.

Submit​

This API call is used to submit a set of recurring payment against a payment token. The payment token needs to be associated with a recurring payment for this to be possible

Request and Response snippet​

/v2/pay/submitRecurring
{
  "echoData": "123",
  "traceId": "00000000000100001",
  "paymentToken": "348348934834934",
  "additionalData": "additional",
  "amount": 2000,
  "customerId": "customer01",
  "notifications": {
    "notificationUrl": "https://www.merchant.com/notify"
  },
  "electronicReceipt": {
    "method": 0,
    "address": "27721234567"
  }
}

echoData <string | optional> : Any value that needs to be echoed in the resulting notifications message and the message posted to the callback URL

traceId <string | required> : (12 - 99 characters long) A unique identifier for transaction tracing purposes

paymentToken <interger | required> : (19 characters) The payment token identifier.

additionalData <type | optional> : (9999 character maximum) Any other data required for the transaction using the VodaPay Gateway Additional Data Token format.Further tokens may be introduced in the future.

amount <boolean | required> : The amount of the transaction in minor currency (integer number of cents) This value can be lower than the original purchase amount, but may not be higher than the purchase amount.

customerId <boolean | conditional> : This is a boolean value that determines if the payment is an immediate payment or a delayed payment.

notifications <string | optional>

  • notificationUrl <string | optional> : (255 character maximum) A URL to which the result of the payment will be sent to notify the integrating party of the result of the API call.

electronicReceipt <string | optional>

  • method <interger | optional> : The method in which the electronicReceipt is to be submitted to the customer

    • 0 = SMS
    • 1 = email

  • address <string | required if "method" is populated> : (255 character maximum) The address which the e-receipt is to be sent